---
title: 'Calendar events'
description: 'Learn how events work in the Schedule-X calendar.'
---

# Events

## Properties

| Property                     | Type                                                      | Description                                                | Required |
|------------------------------|-----------------------------------------------------------|------------------------------------------------------------|----------|
| `id`                         | `string` or `number`                                      | A unique identifier for the event.                         | Yes      |
| `start`                      | `Temporal.PlainDate` or `Temporal.ZonedDateTime`          | The start time of the event.                               | Yes      |
| `end`                        | `Temporal.PlainDate` or `Temporal.ZonedDateTime`          | The end time of the event.                                 | Yes      |
| `title`                      | `string`                                                  | The title of the event.                                    | No       |
| `description`                | `string`                                                  | A description of the event.                                | No       |
| `location`                   | `string`                                                  | The location of the event.                                 | No       |
| `people`                     | `string[]`                                                | Names of the participants                                  | No       |
| `calendarId`                 | `string`                                                  | id of the calendar. See "calendars" section                | No       |
| `_options`                   | [See "_options" section](/docs/calendar/events/#_options) | Configuration for the event.                               | No       |
| `_customContent.timeGrid`    | `string`                                                  | Custom HTML to display in the time grid of week/day views. | No       |
| `_customContent.dateGrid`    | `string`                                                  | Custom HTML to display in the date grid of week/day views. | No       |
| `_customContent.monthGrid`   | `string`                                                  | Custom HTML to display in the month view.                  | No       |
| `_customContent.monthAgenda` | `string`                                                  | Custom HTML to display in the month agenda view.           | No       |

## Other properties

Since you may want to add additional properties to your events, that carry meaning in the business logic of your
application, you are free to do so. The calendar will simply ignore the existence of them and return them back to
you upon interacting with the events.

## Event time

The timestamps of an event can have two different formats: `Temporal.PlainDate` or `Temporal.ZonedDateTime`. These cannot be mixed
within the same event. For example:

1. **Timed events** - Events that have a start and end time such as:

```js
const timedEvent = {
  id: 1,
  start: Temporal.ZonedDateTime.from('2025-10-01T20:15:00+02:00[Europe/Berlin]'),
  end: Temporal.ZonedDateTime.from('2025-10-01T21:15:00+02:00[Europe/Berlin]'),
}
```

2. **Full day events** - Events that span the entire day such as:

```js
const fullDayEvent = {
  id: 2,
  start: Temporal.PlainDate.from('2025-10-01'),
  end: Temporal.PlainDate.from('2025-10-01'),
}
```

Both of these types have the possibility to be either a **single day event** or a **multi day event**. If you want some examples for how to convert
different date and time formats to Temporal, see the [Temporal](/docs/calendar/temporal#converting-different-date-and-time-formats-to-temporal) section.

## _options

Configure the behavior of individual events by adding an `_options` object to the event. All the following
properties are optional:

| Property          | Type       | Description                             | Default     |
|-------------------|------------|-----------------------------------------|-------------|
| disableDND        | `boolean`  | Disables drag and drop for the event.   | `undefined` |
| disableResize     | `boolean`  | Disables resizing for the event.        | `undefined` |
| additionalClasses | `string[]` | Additional classes to add to the event. | `undefined` |


## Updating events

If you want to get, update or remove events after rendering the calendar, you need to use the [events service plugin](/docs/calendar/plugins/events-service).

## Example

```ts
import { createCalendar } from '@schedule-x/calendar'
import '@schedule-x/theme-default/dist/index.css'

const calendar = createCalendar({
  // ... other config
  events: [
    {
      id: 1,
      title: 'Coffee with John',
      start: Temporal.ZonedDateTime.from('2023-11-04T10:05:00+01:00[Europe/Berlin]'),
      end: Temporal.ZonedDateTime.from('2023-11-04T10:35:00+01:00[Europe/Berlin]'),
    },
    {
      id: 2,
      title: 'Ski trip',
      start: Temporal.PlainDate.from('2023-12-04'),
      end: Temporal.PlainDate.from('2023-12-06'),
    },
  ],
})

calendar.render(document.getElementById('calendar'))
```
